Java AI Coding Harness Engineering 五条方法论

核心观点

Java 微服务项目的 AI Coding 体验比前端/Python 差一个量级，根因不是 AI 能力不行，而是微服务架构天然不 AI 友好——项目在本地跑不起来，AI 就无法自主验证。解决方案是 Harness Engineering：构建让 AI 能在本地完成"编辑→运行→验证→修复"闭环的工程环境。

文章从一个阿里内部 Agent 运行时平台（依赖 OSS/远程沙箱/HSF/TDDL/Diamond/Switch 全套云端基础设施）的实际改造出发，给出了可复用的方法论。

问题本质

前端/CLI/Python 项目：编辑代码 → 本地运行 → 测试验证 → AI 读取结果 → 自动修复 → 再次验证，整个循环本地完成，AI 可以自主迭代几十轮。

Java 微服务项目：核心闭环断裂。一个 @Autowired 背后可能牵着一整套分布式基础设施（HSF/TDDL/Diamond/Switch/MetaQ），本地 mvn spring-boot:run 直接失败。AI 每做一步都得等人推预发验证，单次迭代从 30 秒变成 30 分钟。

三条改造原则

1. 依赖倒置，接口先行

上层逻辑只依赖抽象接口，云端和本地是接口的不同实现。

StorageAdapter (接口)
  ├── OssStorageAdapter (线上，走 OSS SDK)
  └── LocalStorageAdapter (本地，走 java.nio.file)
CommandExecutor (接口)
  ├── SandboxCommandExecutor (线上，调远程沙箱 API)
  └── LocalCommandExecutor (本地，ProcessBuilder + bash -c)

切换运行环境只是换一个接口实现，不用重写上层逻辑。

2. 零侵入，Profile 隔离

本地改造不能让线上代码路径多走一行额外代码。

• @Profile("local") 装配本地 Bean，@Profile("!local") 守卫线上 Bean
• @ComponentScan 正则过滤整包排除（远程沙箱/OpenTelemetry）
• @Nullable 参数注入 + null 检查决定走哪条路径
• 检验标准：删掉所有本地相关代码后，线上行为完全不变

侵入性分级：零侵入（新建文件）> 极低（加 implements）> 低（类型上提到接口）> 中等（新增可选参数）

3. 工具 AI 化：CLI 优先

AI Agent 的能力边界 = 它能调用的工具的边界。GUI 对 AI 不可见，CLI 才是 AI 能用的东西。

工具 AI 化优先级：

1. CLI — 直接可用（mw-cli, mvn, git, arthas）
2. MCP Server — 协议适配（数据库查询、监控数据）
3. Skill / Tool — 自定义封装（配置查询、服务诊断）
4. GUI — 不可用（Web 管理台、IDE 插件）

用 CLI 桥接企业内部系统（mw diamond get 查配置、mw hsf address 查服务地址），输出结构化文本 AI 直接解析。

五条方法论

1. 找到最小可运行子集：不需要搬所有线上能力到本地，只需核心链路跑通的最小依赖集（本例：数据库+文件系统+命令执行）
2. 替代而非模拟：H2 不是"模拟" MySQL 而是真实数据库跑真实 SQL；LocalCommandExecutor 就是执行真实 bash 命令。AI 在本地发现的问题线上大概率也会有
3. 脚本化一切人工操作：凡是需要登录管理台/复制配置/点击按钮的操作都应有对应脚本。脚本就是 AI 的手，没有脚本 AI 就是残废的
4. 分层隔离，逐层验证：先编译 → 再启动 → 再接口调通 → 再端到端。每层有对应验证手段（mvn compile、health check、API 冒烟测试、Playwright E2E）
5. 让 AI 成为改造的参与者：先手动搞定核心部分确保本地能跑，之后 AI 在本地闭环里自己迭代后续实现。正向循环：每完成一步改造 AI 能做的事多一点

改造效果

配合 Harness 落地

CLAUDE.md

100 行以内，告诉 AI：项目是什么、怎么构建、怎么测试、本地怎么启动。

验证脚本

scripts/verify-local.sh：编译检查 → 单元测试 → 本地启动 health check → 文件系统闭环检查。AI 改完代码跑一次就知道环境是否正常。

端到端冒烟测试

tests/smoke/local-chat-smoke.mjs：Health Check → API 验证（SSE 流式调用 + 数据落库） → UI E2E（Playwright）。几秒钟知道核心链路有没有挂。

本地化改造全景图

Harness Engineering Checklist

• 可运行性：一条命令启动？外部依赖有本地替代？接口抽象+Profile 切换？
• 可测试性：AI 能本地跑测试并读结果？核心逻辑有单测？端到端能自动完成？
• 可观测性：日志结构化可 grep？有 CLI 诊断工具？命令行获取运行时状态？
• 工具 AI 化：运维工具有 CLI？配置可命令行查询？有 MCP/Skill 暴露内部系统？
• 隔离性：@Profile 隔离？零侵入？删本地代码线上不变？

后续方向

JVM 诊断能力工具化：超时自动 jstack、Skill 封装 Arthas 的 watch/trace/tt、异常 JSON 格式输出让 AI 直接解析定位代码行。目标是 AI 在本地完全自主跑完"发现问题→定位原因→修复代码→验证修复"整个循环。

关联页面

• Harness Engineering
• AI Coding
• Context Engineering
• 依赖倒置原则
• Spring Profile